The section describes the programming interface of the DSPI master mode Peripheral driver. More...

Data Structures
struct	dspi_device_t
	Data structure containing information about a device on the SPI bus. More...

struct	dspi_master_state_t
	Runtime state structure for the DSPI master driver. More...

struct	dspi_master_user_config_t
	The user configuration structure for the DSPI master driver. More...

Init and shutdown
dspi_status_t	dspi_master_init (uint32_t instance, dspi_master_state_t dspiState, const dspi_master_user_config_t userConfig, uint32_t *calculatedBaudRate)
	Initialize a DSPI instance for master mode operation. More...

void	dspi_master_shutdown (dspi_master_state_t *dspiState)
	Shuts down a DSPI instance. More...

void	dspi_master_configure_modified_transfer_format (dspi_master_state_t *dspiState, bool enableOrDisable, dspi_master_sample_point_t samplePnt)
	Configures the DSPI modified transfer format in master mode. More...

Bus configuration
dspi_status_t	dspi_master_configure_bus (dspi_master_state_t dspiState, const dspi_device_t device, uint32_t *calculatedBaudRate)
	Configures the DSPI port physical parameters to access a device on the bus. More...

Blocking transfers
dspi_status_t	dspi_master_transfer (dspi_master_state_t dspiState, const dspi_device_t restrict device, const uint8_t sendBuffer, uint8_t receiveBuffer, size_t transferByteCount, uint32_t timeout)
	Performs a blocking SPI master mode transfer. More...

Non-blocking transfers
dspi_status_t	dspi_master_transfer_async (dspi_master_state_t dspiState, const dspi_device_t restrict device, const uint8_t sendBuffer, uint8_t receiveBuffer, size_t transferByteCount)
	Performs a non-blocking SPI master mode transfer. More...

dspi_status_t	dspi_master_get_transfer_status (dspi_master_state_t dspiState, uint32_t framesTransferred)
	Returns whether the previous transfer is finished. More...

dspi_status_t	dspi_master_abort_transfer (dspi_master_state_t *dspiState)
	Terminates an asynchronous transfer early. More...

DSPI Master Driver

Overview

The DSPI master mode peripheral driver transfers data to and from external devices on the DSPI bus in master mode. It supports transferring buffers of data with a single function call.

Run-time state structs

The DSPI master driver uses a run-time state struct dspi_master_state_t to track of the ongoing data transfer. The struct holds data that the DSPI master peripheral driver uses to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user is only responsible to pass the memory for this run-time state structure and the DSPI master driver will fill out the members.

User config structs

The DSPI master driver uses instances of the user configuration structure dspi_master_user_config_t for the DSPI master driver. For this reason, the user can configure the most common settings of the DSPI peripheral with a single function call.

Device structs

The DSPI master driver uses instances of the dspi_device_t structure to represent the SPI bus configuration required to communicate to an external device that is connected to the bus.The device struct can be passed to the data transfer functions, and the bus will be reconfigured before the transfer is started. Alternatively, the user can configure the SPI bus for a device manually. For instance, if there is only one device connected to the bus, the user might configure it only once.

Initialization

To initialize the DSPI master driver, call the dspi_master_init() function and and pass the instance number of the DSPI peripheral, the user config of type dspi_master_user_config_t , a pointer to the variable for retrieving the calculated baud rate (this can be a NULL), and memory allocation for the run-time state structure used by the master driver to keep track of data transfers. For example, to use DSPI1, pass a value of 1 to the init function. This is an example for the other parameters.Example code to initialize and configure the driver:

/* Set up and init the master  */
dspi_master_state_t dspiMasterState;
uint32_t calculatedBaudRate;
/* configure the members of the user config */
dspi_master_user_config_t userConfig;
userConfig.isChipSelectContinuous = false;
userConfig.isSckContinuous = false;
userConfig.pcsPolarity = kDspiPcs_ActiveLow;
userConfig.whichCtar = kDspiCtar0;
userConfig.whichPcs = kDspiPcs1;
/* init the DSPI module */
dspi_master_init(masterInstance, &dspiMasterState, &userConfig, &calculatedBaudRate);
// Define bus configuration.
dspi_device_t spiDevice;
spiDevice.dataBusConfig.bitsPerFrame = 16;
spiDevice.dataBusConfig.clkPhase = kDspiClockPhase_FirstEdge;
spiDevice.dataBusConfig.clkPolarity = kDspiClockPolarity_ActiveHigh;
spiDevice.dataBusConfig.direction = kDspiMsbFirst;
spiDevice.bitsPerSec = 500000;
/* configure the SPI bus */
dspi_master_configure_bus(&dspiMasterState, &spiDevice, &calculatedBaudRate); 

Transfers

The driver supports two different modes for transferring data: blocking and non-blocking (async). The dspi_master_transfer() is the blocking transfer function. The dspi_master_transfer_async() is a non-blocking function.Example of a blocking transfer:

/* Function prototype */
status_t dspi_master_transfer(dspi_master_state_t * dspiState,
                              const dspi_device_t * restrict device,
                              const uint8_t * sendBuffer,
                              uint8_t * receiveBuffer,
                              uint32_t transferByteCount,
                              uint32_t timeout);
/* Example function call */                              
dspi_master_transfer(&dspiMasterState, NULL, s_dspiSourceBuffer[masterInstance], s_dspiSinkBuffer[masterInstance], 32, 1);

Example of a nonb-locking transfer:

/* Function prototype */
status_t dspi_master_transfer_async(dspi_master_state_t * dspiState,
                                    const dspi_device_t * restrict device,
                                    const uint8_t * sendBuffer,
                                    uint8_t * receiveBuffer,
                                    uint32_t transferByteCount);
/* Example function call */                              
dspi_master_transfer_async(&dspiMasterState, NULL, s_dspiSourceBuffer[masterInstance], s_dspiSinkBuffer[masterInstance], 32);
/* For non-blocking/a-sync transfers, need to check back to get transfer status, for example */
/* Where framesXfer returns the number of frames transferred */
dspi_master_get_transfer_status(&dspiMasterState, &framesXfer);

Data Structure Documentation

struct dspi_device_t

The user must fill out these members to set up the DSPI master to properly communicate with the SPI device.

Data Fields
uint32_t	bitsPerSec
	Baud rate in bits per second. More...

dspi_data_format_config_t	dataBusConfig

Field Documentation

uint32_t dspi_device_t::bitsPerSec

struct dspi_master_state_t

This struct holds data that is used by the DSPI master peripheral driver to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user must pass the memory for this run-time state structure and the DSPI master driver will fill out the members.

Data Fields
uint32_t	instance
	DSPI module instance number.

dspi_ctar_selection_t	whichCtar
	Desired Clock and Transfer Attributes Register (CTAR)

uint32_t	bitsPerFrame
	Desired number of bits per frame.

dspi_which_pcs_config_t	whichPcs
	Desired Peripheral Chip Select (pcs)

bool	isChipSelectContinuous
	Option to enable the continuous assertion of chip select between transfers.

uint32_t	dspiSourceClock
	Module source clock.

volatile bool	isTransferInProgress
	True if there is an active transfer. More...

bool	isTransferAsync
	Whether the transfer is asynchronous (needed in IRQ). More...

const uint8_t *restrict	sendBuffer
	The buffer from which transmitted bytes are taken. More...

uint8_t *restrict	receiveBuffer
	The buffer into which received bytes are placed. More...

volatile size_t	remainingSendByteCount
	Number of bytes remaining to send. More...

volatile size_t	remainingReceiveByteCount
	Number of bytes remaining to receive. More...

sync_object_t	irqSync
	Used to wait for ISR to complete its business. More...

Field Documentation

volatile bool dspi_master_state_t::isTransferInProgress

bool dspi_master_state_t::isTransferAsync

const uint8_t* restrict dspi_master_state_t::sendBuffer

uint8_t* restrict dspi_master_state_t::receiveBuffer

volatile size_t dspi_master_state_t::remainingSendByteCount

volatile size_t dspi_master_state_t::remainingReceiveByteCount

sync_object_t dspi_master_state_t::irqSync

struct dspi_master_user_config_t

Use an instance of this struct with the dspi_master_init(). This allows the user to configure the most common settings of the DSPI peripheral with a single function call.

Data Fields
dspi_ctar_selection_t	whichCtar
	Desired Clock and Transfer Attributes Register(CTAR)

bool	isSckContinuous
	Disable or Enable continuous SCK operation.

bool	isChipSelectContinuous
	Option to enable the continuous assertion of chip select between transfers.

dspi_which_pcs_config_t	whichPcs
	Desired Peripheral Chip Select (pcs)

dspi_pcs_polarity_config_t	pcsPolarity
	Peripheral Chip Select (pcs) polarity setting. More...

Field Documentation

dspi_pcs_polarity_config_t dspi_master_user_config_t::pcsPolarity

Function Documentation

dspi_status_t dspi_master_init	(	uint32_t	instance,
		dspi_master_state_t *	dspiState,
		const dspi_master_user_config_t *	userConfig,
		uint32_t *	calculatedBaudRate
	)

This function initializes the run-time state structure to track the ongoing transfers, ungates the clock to the DSPI module, resets the DSPI module, initializes the module to user defined settings and default settings, configures the IRQ state structure, enables the module-level interrupt to the core, and enables the DSPI module. The CTAR parameter is special in that it allows the user to have different SPI devices connected to the same DSPI module instance in addition to different peripheral chip selects. Each CTAR contains the bus attributes associated with that particular SPI device. For most use cases where only one SPI device is connected per DSPI module instance, use CTAR0. This is an example to set up the dspi_master_state_t and the dspi_master_user_config_t parameters and to call the dspi_master_init function by passing in these parameters:

dspi_master_state_t dspiMasterState; <- the user simply allocates memory for this struct
uint32_t calculatedBaudRate;
dspi_master_user_config_t userConfig; <- the user fills out members for this struct
userConfig.isChipSelectContinuous = false;
userConfig.isSckContinuous = false;
userConfig.pcsPolarity = kDspiPcs_ActiveLow;
userConfig.whichCtar = kDspiCtar0;
userConfig.whichPcs = kDspiPcs0;
dspi_master_init(masterInstance, &dspiMasterState, &userConfig, &calculatedBaudRate);

Parameters

instance	The instance number of the DSPI peripheral.
dspiState	The pointer to the DSPI master driver state structure. The user must pass the memory for this run-time state structure and the DSPI master driver will fill out the members. This run-time state structure keeps track of the transfer in progress.
userConfig	The dspi_master_user_config_t user configuration structure. The user must fill out the members of this structure and pass the pointer of this struct into the function.
calculatedBaudRate	The calculated baud rate passed back to the user to determine if the calculated baud rate is close enough to meet the needs. The value returned may be 0 if the user decides to set the baud rate to 0 in the user configuration struct. The user can later configure the baud rate via the dspi_master_configure_bus function, and hence may not need to configure the baud rate in the dspi_master_init function.

Returns: An error code or kStatus_DSPI_Success.

void dspi_master_shutdown ( dspi_master_state_t * dspiState )

This function resets the DSPI peripheral, gates its clock, and disables the interrupt to the core.

Parameters

dspiState The pointer to the DSPI master driver state structure.

void dspi_master_configure_modified_transfer_format	(	dspi_master_state_t *	dspiState,
		bool	enableOrDisable,
		dspi_master_sample_point_t	samplePnt
	)

This function allows the user to enable or disable (default setting) the modified transfer format. The modified transfer format is supported to allow high-speed communication with peripherals that require longer setup times. The module can sample the incoming data later than halfway through the cycle to give the peripheral more setup time. The data-in sample point can also be configured in this function. Note that the data-in sample point setting is valid only when the CPHA bit in the CTAR is cleared (when the dspi_clock_phase_t is set to kDspiClockPhase_FirstEdge in the dspi_data_format_config_t).

Parameters

dspiState	The pointer to the DSPI master driver state structure.
enableOrDisable	Enables (true) or disables(false) the modified transfer (timing) format.
samplePnt	Selects when the data in (SIN) is sampled, of type dspi_master_sample_point_t. This value selects either 0, 1, or 2 system clocks between the SCK edge and the SIN (data in) sample.

dspi_status_t dspi_master_configure_bus	(	dspi_master_state_t *	dspiState,
		const dspi_device_t *	device,
		uint32_t *	calculatedBaudRate
	)

The term "device" is used to indicate the SPI device for which the DSPI master is communicating. The user has two options to configure the device parameters: either pass in the pointer to the device configuration structure to the desired transfer function (see dspi_master_transfer or dspi_master_transfer_async) or pass it in to the dspi_master_configure_bus function. The user can pass in a device structure to the transfer function which contains the parameters for the bus (the transfer function will then call this function). However, the user has the option to call this function directly especially to get the calculated baud rate, at which point they may pass in NULL for the device struct in the transfer function (assuming they have called this configure bus function first). This is an example to set up the dspi_device_t structure to call the dspi_master_configure_bus function by passing in these parameters:

dspi_device_t spiDevice;
spiDevice.dataBusConfig.bitsPerFrame = 16;
spiDevice.dataBusConfig.clkPhase = kDspiClockPhase_FirstEdge;
spiDevice.dataBusConfig.clkPolarity = kDspiClockPolarity_ActiveHigh;
spiDevice.dataBusConfig.direction = kDspiMsbFirst;
spiDevice.bitsPerSec = 50000;
dspi_master_configure_bus(&dspiMasterState, &spiDevice, &calculatedBaudRate);

Parameters

dspiState	The pointer to the DSPI master driver state structure.
device	Pointer to the device information struct. This struct contains the settings for the SPI bus configuration. The device parameters are the desired baud rate (in bits-per-sec), and the data format field which consists of bits-per-frame, clock polarity and phase, and data shift direction.
calculatedBaudRate	The calculated baud rate passed back to the user to determine if the calculated baud rate is close enough to meet the needs. The baud rate never exceeds the desired baud rate.

Returns: An error code or kStatus_DSPI_Success.

dspi_status_t dspi_master_transfer	(	dspi_master_state_t *	dspiState,
		const dspi_device_t *restrict	device,
		const uint8_t *	sendBuffer,
		uint8_t *	receiveBuffer,
		size_t	transferByteCount,
		uint32_t	timeout
	)

This function simultaneously sends and receives data on the SPI bus, as SPI is naturally a full-duplex bus. The function does not return until the transfer is complete.

Parameters

dspiState	The pointer to the DSPI master driver state structure.
device	Pointer to the device information struct. This struct contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the dspi_master_configure_bus function.
sendBuffer	The pointer to the data buffer of the data to send. You may pass NULL for this parameter and bytes with a value of 0 (zero) will be sent.
receiveBuffer	Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored.
transferByteCount	The number of bytes to send and receive.
timeout	A timeout for the transfer in microseconds. If the transfer takes longer than this amount of time, the transfer is aborted and a kStatus_SPI_Timeout error returned.

Return values

kStatus_DSPI_Success	The transfer was successful.
kStatus_DSPI_Busy	Cannot perform another transfer because a transfer is already in progress.
kStatus_DSPI_Timeout	The transfer timed out and was aborted.

dspi_status_t dspi_master_transfer_async	(	dspi_master_state_t *	dspiState,
		const dspi_device_t *restrict	device,
		const uint8_t *	sendBuffer,
		uint8_t *	receiveBuffer,
		size_t	transferByteCount
	)

This function returns immediately. The user must check back to check whether the transfer is complete (using the dspi_master_get_transfer_status function). This function simultaneously sends and receives data on the SPI bus, as SPI is naturally a full-duplex bus.

Parameters

dspiState	The pointer to the DSPI master driver state structure.
device	Pointer to the device information struct. This struct contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the dspi_master_configure_bus function.
sendBuffer	The pointer to the data buffer of the data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) are sent.
receiveBuffer	Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored.
transferByteCount	The number of bytes to send and receive.

Return values

kStatus_DSPI_Success	The transfer was successful.
kStatus_DSPI_Busy	Cannot perform another transfer because a transfer is already in progress.

dspi_status_t dspi_master_get_transfer_status	(	dspi_master_state_t *	dspiState,
		uint32_t *	framesTransferred
	)

When performing an a-sync transfer, the user can call this function to ascertain the state of the current transfer: in progress (or busy) or complete (success). In addition, if the transfer is still in progress, the user can get the number of words that have been transferred up to now.

Parameters

dspiState	The pointer to the DSPI master driver state structure
framesTransferred	Pointer to value that is filled in with the number of frames that have been sent in the active transfer. A frame is defined as the number of bits per frame.

Return values

kStatus_DSPI_Success	The transfer has completed successfully.
kStatus_DSPI_Busy	The transfer is still in progress. wordsTransferred will be filled with the number of words that have been transferred so far.

dspi_status_t dspi_master_abort_transfer ( dspi_master_state_t * dspiState )

During an a-sync transfer, the user has the option to terminate the transfer early if the transfer is still in progress.

Parameters

dspiState The pointer to the DSPI master driver state structure.

Return values

kStatus_DSPI_Success	The transfer was successful.
kStatus_DSPI_NoTransferInProgress	No transfer is currently in progress.

Data Structures

Init and shutdown

Bus configuration

Blocking transfers

Non-blocking transfers

DSPI Master Driver

Overview

Run-time state structs

User config structs

Device structs

Initialization

Transfers

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Function Documentation